<?php

/**
 * Ignus Framework
 *
 * @author Sergey Palyanov <sergey.palyanov@gmail.com>
 * @link http://code.google.com/p/ignus-php/
 * @license http://apache.org/licenses/LICENSE-2.0
 * @package Ignus
 * @subpackage Util
 * @since 0.1
 */

namespace Ignus\Util;

/**
 * @package Ignus
 * @subpackage Util
 * @since 0.1
 */
interface Map
{
    /**
     *
     * @abstract
     * @return integer Number of entries in a map
     */
    public function size();

    /**
     * Return true if map has no entries
     * @abstract
     * @return boolean True if map has no entries
     */
    public function isEmpty();

    /**
     * Return true if there is entry with such key in map
     * @abstract
     * @param mixed $key Key to check
     * @return boolean True if map has entry with such key
     */
    public function containsKey($key);

    /**
     * Return value associated with specified key
     * @abstract
     * @param mixed $key Key of entry
     * @return mixed Entry value
     */
    public function get($key);

    /**
     * Put new entry to map. If there is already a value associated with same key,
     * it will be replaced with new value.
     * @abstract
     * @param mixed $key Key of entry
     * @param mixed $value Value to associate with key
     * @return mixed Previous value of replaced entry or null
     *  if no entry was replaced
     */
    public function put($key, $value);

    /**
     * Remove entry from map and return its value
     * @abstract
     * @param mixed $key Key of entry
     * @return mixed Value of removed entry
     */
    public function remove($key);

    /**
     * Import all entries from another map
     * @abstract
     * @param Map $source Source map
     * @return void
     */
    public function putAll(Map $source);

    /**
     * Removes all entries from map
     * @abstract
     * @return void
     */
    public function clear();
}
